<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>s6: dynamic instantiation</title>
    <meta name="Description" content="s6: dynamic instantiation" />
    <meta name="Keywords" content="s6 instances dynamic instantiation" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">s6</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>

<h1> Dynamic instantiation </h1>

<p>
 An <em>instanced service</em> is a parameterized service that you want to
run several copies of, with only the parameter changing. Each copy of the
service is called an <em>instance</em>.
</p>

<p>
 With s6, a <a href="servicedir.html">service directory</a> can only
handle one process at a time. So, if we want instanced services, there
will have to be one service directory per instance, always.
</p>

<p>
 <em>Static instantiation</em> means that the set of possible instances
is finite and known in advance. With s6, it means that all the service
directories for all possible instances are created, typically by a
preprocessor, and instances are treated like regular services.
</p>

<p>
 <em>Dynamic instantiation</em> means that instances are created
on demand instead of preallocated. Starting with version 2.11.2.0, s6
provides a few tools to help users set up and manage dynamically
instanced services.
</p>

<h2> How to make a dynamically instanced service under s6 </h2>

<ul>
 <li> Write a template for a service directory that would run under
<a href="s6-supervise.html">s6-supervise</a>.
The <tt>run</tt> script should take the name of the instance as its
first argument; the <tt>finish</tt> script, if present, should take the name
of the instance as its third argument. </li>
 <li> Call the <a href="s6-instance-maker.html">s6-instance-maker</a> program
with this template as first argument, and a path <em>dir</em> as second
argument. <a href="s6-instance-maker.html">s6-instance-maker</a> will create
a service directory in <em>dir</em>. This is an offline tool: it does not
interact with any currently active services or supervision trees. </li>
 <li> Supervise <em>dir</em> by adding it to your regular
<a href="scandir.html">scan directory</a>. This will be your instanced
service, but it's not running any instances yet. It is, instead, a nested
supervision tree - the instanced service is an
<a href="s6-svscan.html">s6-svscan</a> process that will supervise all the
instances. </li>
 <li> Create and delete instances at will with the
<a href="s6-instance-create.html">s6-instance-create</a> and
<a href="s6-instance-delete.html">s6-instance-delete</a> programs; you
can list all the available instances with
<a href="s6-instance-list.html">s6-instance-list</a>.
 These tools are <em>online</em>: they work with live service directories,
i.e. that are being supervised by <a href="s6-supervise.html">s6-supervise</a>.
 <li> Instances are regular supervised processes. You can control individual
instances with <a href="s6-instance-control.html">s6-instance-control</a>,
and check their status with
<a href="s6-instance-status.html">s6-instance-status</a>. These tools
are online as well. </li>
</ul>

<h2> Internal workings </h2>

<p>
This section is not normative; users should not rely on it. It is only
here for informational purposes.
</p>

<ul>
 <li> The service directory created by <a href="s6-instance-maker.html">s6-instance-maker</a>
has three specific subdirectories in it: <tt>instance</tt> and <tt>instances</tt>, which
are initially empty, and <tt>template</tt>, storing the template service directory. </li>
 <li> When the service is active, there is an <a href="s6-svscan.html">s6-svscan</a>
process running on <tt>instance</tt>. </li>
 <li> <a href="s6-instance-create.html">s6-instance-create</a> makes a copy of
<tt>template</tt> into <tt>instances/<em>name</em></tt>, and
<a href="s6-svlink.html">s6-svlink</a>s <tt>instances/<em>name</em></tt> to
<tt>instance</tt>. When it returns, there is an <a href="s6-supervise.html">s6-supervise</a>
process running on <tt>instance/<em>name</em></tt>, and the instance may be up
or not depending on the given options. </li>
 <li> <a href="s6-instance-control.html">s6-instance-control</a> is syntactic sugar
around <a href="s6-svc.html">s6-svc</a> on <tt>instance/<em>name</em></tt>. </li>
 <li> <a href="s6-instance-status.html">s6-instance-status</a> is syntactic sugar
around <a href="s6-svstat.html">s6-svstat</a> on <tt>instance/<em>name</em></tt>. </li>
 <li> <a href="s6-instance-delete.html">s6-instance-delete</a> is syntactic sugar
around <a href="s6-svunlink.html">s6-svunlink</a> on <tt>instance/<em>name</em></tt>. </li>
 <li> <a href="s6-instance-list.html">s6-instance-list</a> is roughly equivalent
to <code>ls -1 instance </code>. </li>
</ul>

<h2> Notes </h2>

<ul>
 <li> This implementation of dynamic instances may seem expensive: it
creates one <a href="s6-svscan.html">s6-svscan</a> process per
instanced service, and one <a href="s6-supervise.html">s6-supervise</a>
process per instance. However, remember that these processes use very
little private memory, so having additional copies of them is far less
expensive than it looks. It's really a convenient way to implement the
feature by reusing existing code. </li>
</ul>

</body>
</html>
